<html>
	<title>runSingleTCW</title>
	<body style="padding:20px;width:650px;font-family:Times">
		
<h2>singleTCW Manager</h2>
<br>The main data type is the "sequence", which could be an TCW assembled contig, transcripts
with optional read counts, or proteins with spectral counts.  If sequences, such as ESTs, are assembled,
the resulting contig consensus sequence has read counts from the assembly.
<h3>Add Project</h3> 
You will be prompted for a <i>project-name</i>. Keep it short but descriptive. The following will occur
after you entered the name and OK:

<table border=0 cellspacing=3>
<tr><td valign="top">Directory<td> A directory named <i>project-name</i> will be created
under /libraries and /projects, where information is stored for the building the project.
<tr><td valign="top"><i>Database</i><td>The <i>project-name</i> will be entered as the database name with a
"sTCW_" prefix -- do not remove the prefix. 
<tr><td valign="top" nowrap><i>singleTCW ID</i><td> The <i>project-name</i> is entered, which you may change.
Keep this name short but descriptive, e.g. about 3 letters.
</table>
Though it is not required, you may put your library files in your project directory
under /libraries (e.g.
see /TCW/libraries/demoOlD_DE). You may create this directory yourself, which will
automatically be listed on the Project selector.
<p>
Additionally, you may change the following:
<table border=0 cellspacing=3>
<tr><td valign="top"><i>Host</i><td> localhost is the default, and you may select a different
host, if more are listed in the HOSTS.cfg file. Whichever host you select (including localhost)
must have an entry in HOSTS.cfg, and the user/password listed there must be valid
for the MySQL on that host. 
<tr><td valign="top">#CPUs</i><td>If your machine has multiple CPUs, enter the number so that
BLAST will be executed in parallel.
</table>

<h3>Existing project</h3>
<table border=0 cellspacing=3>
<tr><td valign="top">Project<td>Allows you to select a project, where your projects are the directories under
the /libraries directory.
<tr><td valign="top"><i>Save</i><td> Save all information you have added. The information is also saved
whenever you execute a function (Load Libraries, Instantiate and Annotate Sequences).
Information about the libraries is stored in /libraries/<i>project-name</i>/LIB.cfg and
information about the assembly and annotation is stored in /projects/<i>project-name</i>/sTCW.cfg.
 
<tr><td valign="top"><i>Remove</i></td><td valign="top"> Remove (i) existing annotation, (2) 
the database, (3) the files from disk (i.e. your project
directory under /libraries and /project), or (4) the database and files.</td></tr>
<tr><td valign="top"><i>Overview</i><td> Shows the overview page of the selected project. There will only be
an overview page if Load Libraries has been executed.

</table>

<h3>LOAD LIBRARIES</h3>
You should read the User Guide and create the demo project in order to fully understand this. But 
briefly, add Sequence Libraries with the Add button, where the libraries can be: 
ESTs or other nucleotide sequences to be assembled, transcript (i.e. already assembled reads), 
or protein sequences. You can make changes with
the Edit button, but once you have executed "Load Libraries", you can only change the
Attribute data (e.g. tissue type).
<p>For transcripts and protein, you can also add the associated read or spectral count files, as follows:
<table border=0 cellspacing=2>
<tr><td valign="top"><i>Add</i><td>When you select this button, a new panel will appear with a Help to give more
detail. Briefly, when you add a sequence library, 
you may define the count libraries associated with a sequence (transcript or protein).  
The "Keep" will take you back to this main window,
where the count libraries will be shown in the second table, and the Reps column will be initialized to 1.
<tr><td valign="top"><i>Define Replicas</i><td> This function
will allows you to group replicas into libraries. 
<tr><td valign="top"><i>Edit Attributes</i><td>After you have defined replicas (if needed), then edit the attributes of the read count
libraries with "Edit Attributes". Attributes can be added or edited after the database is created.
</table>
Note: if you are creating multiple singleTCWs to compare in multiTCW, it is very important that
you use the same library names for equivalent libraries across the species to be compared, e.g.
if you are comparing species maize and rice and they both have the library 'leaf', make sure
they are named the same.

<h3>RUN ASSEMBLY</h3>
If the input is nucleotides, they may be assembled. Protein and transcript sequences
can be loaded without assembly. 
<p>
If you want the reads and/or transcripts to be assembled, uncheck Skip Assembly.
<p>
If you want to Skip Assembly and have the sequence names from the files used as their Seq ID,
check Use Sequence Name from File. Otherwise, it will generate sequence names using the singleTCW ID. 
<p>
Options: these generally do not need changing.

<h3>RUN ANNOTATION</h3>
Add one or more protein or nucleotide databases (referred to as annoDBs); 
the sequences in the sTCW database will be blasted against them. A script is provided
to download and extract the sequences from UniProt taxonomic databases (/scripts/newUPver.pl).
The Run Annotation works best with the UniProt database, as it can then also extract
the GO, EC, PFam and KEGG identifiers. For GO, you will need the GO database (see /scripts/newGOver.pl).
<p>
If you use databases other then UniProt, you need to make sure there that the descriptor line
for each sequence (i.e. > lines) is formated correctly. Genbank formats are accepted,
plus a generic format (see the online Annotation Guide, section 6).
<p>You have a choice of using blast, usearch or diamond for searching the database sequences
against an annoDB. The path names for the search progams must be in the HOSTS.cfg file. You can either request
a particular search program when you add an annoDB, or use the default "TCW Select" to let
TCW select an appropriate program (see Help on Add/Edit page). 
<p>
You may add all annotation at once, where you define your annoDBs, optionally select
your GO database, and optionally select "Similar Sequences" (see Options), followed by "Annotate Sequences". 
Incremental annotation is suppported as follows: 
<ol>
<li>After adding annotation, you may add new annoDBs or similar Pairs or GO annoations.
<li>Important: Uncheck all annoDBs that have been added (they are in italics). You need to click the
line twice, once to highlight it and once to uncheck.
<li>Execute "Run Annotation".
<br>Reply "n" to the prompt asking if you want to remove the existing annotation.
<br>Reply "y" to the prompt asking if you want to add to existing annotation. 
<br>If you reply "n", it
will abort.
</ol>
You cannot remove part of the existing annotation, but if you need to change something already loaded,
you can remove the existing annotation (with Remove...), then reload the full annotation, 
re-using any of the existing blast files which are still valid:
<ol>
<li>Execute "Run Annotation".
<br>Reply 'y' on the prompt asking if you want to remove the existing annotation.
<br>Reply 'y' to prompts asking if you want to load the existing blast file, unless you
wish to re-run that blast.
</ol>
After all prompts, it will ask you to confirm before it continues with annotation. 

<p>Annotation Interface: 
<ul>
<li>Click a line once to selected it, than a second time to check or un-check the box.
<li>The order of the databases is important when you only want to run the un-annotated sequences 
against a particular database. In that case, the database should be at the end of the list and use "Edit" to
set "Unannotated only". 
</ul>
<h3>Update GO</h3>

If annotation was already run and you just want to add GO annotation to it, or update previous
GO annotation, use this function. TCW GO annotation requires a reference MySQL "GO database"
which must be created beforehand using the provided script newGOver.pl; see online
documentation. Note, this also adds Pfam, Kegg, and EC cross-referencing for the Uniprots. 

<h3>Launch viewSingleTCW</h3>
Launches this program to view the resulting project.

<h3>Launch DE</h3>
Runs edgeR, DEGseq or DESeq to compute differential expression (DE) p-values on selected libraries,
and GOseq to compute the DE of the GOs.
<br>It uses R, which must be installed.
<br><i>It leaves the terminal at the R prompt, and you must type "quit()" to exit R.</i>

<h3>Add Remarks</h3>
You can add remarks from a file, which can be displayed in a column in any table and can
be searched on in the Basic Sequence Query. The file is just a set of rows where the
first word of each row is the sequence ID, and the rest of the row is added 
as the Remark for the sequence. <i>Single and double quotes will be changed to spaces</i>.
<p>
The Remove Remarks removes all remarks.


<h3>Troubleshooting</h3>
<ol>
<li>After a TCW database has been created, runSingleTCW can be used to edit
the metadata (i.e. tissue, etc). This ONLY works right from the TCW directory that has 
the /libraries and /project subdirectories, as it needs to read the LIB.cfg and sTCW.cfg 
project files. It also reads the combined read count file (if there is one).
<li>runSingleTCW will detect certain file format problems, etc, 
but some errors are not found until Load Library.
If that happens, Remove MySQL database, fix the error and restart.
<li>If you have added a library, you can not change anything except the
attributes. If you need to make a change (i.e. rebuild the count file), remove the library
from the "Transcript, Read or Protein Library" table and re-add.
<li>If something appears wrong and you do not know how to fix it, you can remove
the "/libraries/&lt;your project name&gt;/LIB.cfg" file and restart. 
<li>If any process seems to "hang", i.e. no output to terminal for a very long time,
either close the runSingleTCW window or ctrl-C. Then just restart. NOTE: on Macs,
pop-up windows get hidden easy and freeze the main singleTCW window until you acknowledge
the pop-up, so look around for it...
</ol>

